Skip to content

feat(assessors): support AGENTS.md and @ references in CLAUDEmdAssessor #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
chambridge merged 1 commit into from
Jan 16, 2026
Merged

feat(assessors): support AGENTS.md and @ references in CLAUDEmdAssessor #265

chambridge merged 1 commit into from
Jan 16, 2026

Conversation

@chambridge
Copy link
Collaborator

@chambridge chambridge commented Jan 16, 2026

Description

Add comprehensive support for cross-tool compatibility and flexible configuration:

This enhancement enables repositories to:

  1. Share configuration across multiple AI coding assistants
  2. Use flexible @ reference indirection for minimal CLAUDE.md files
  3. Maintain backward compatibility with existing CLAUDE.md workflows

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test coverage improvement

Related Issues

Fixes #244

Changes Made

  • Support CLAUDE.md as symlink to AGENTS.md
  • Support @ reference syntax (@AGENTS.md) for content indirection
  • Accept AGENTS.md as alternative to CLAUDE.md (90/100 score)
  • Detect cross-tool compatibility when both files present
  • Implement path traversal security protection (reject ../ and absolute paths)
  • Add 14 comprehensive unit tests including security validation
  • Add type hints and performance improvements

Testing

  • Unit tests pass (pytest)
  • Integration tests pass
  • Manual testing performed
  • No new warnings or errors

Checklist

  • My code follows the project's code style
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published

Screenshots (if applicable)

Additional Notes

@chambridge @claude
feat(assessors): support AGENTS.md and @ references in CLAUDEmdAssessor
8b312e8 
Add comprehensive support for cross-tool compatibility and flexible configuration:

- Support CLAUDE.md as symlink to AGENTS.md
- Support @ reference syntax (@AGENTS.md) for content indirection
- Accept AGENTS.md as alternative to CLAUDE.md (90/100 score)
- Detect cross-tool compatibility when both files present
- Implement path traversal security protection (reject ../ and absolute paths)
- Add 14 comprehensive unit tests including security validation
- Add type hints and performance improvements

This enhancement enables repositories to:
1. Share configuration across multiple AI coding assistants
2. Use flexible @ reference indirection for minimal CLAUDE.md files
3. Maintain backward compatibility with existing CLAUDE.md workflows

Closes ambient-code#244

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
Signed-off-by: Chris Hambridge <[email protected]>
@github-actions
Copy link
Contributor

github-actions bot commented Jan 16, 2026

📈 Test Coverage Report

Branch Coverage
This PR 62.5%
Main 62.3%
Diff ✅ +0.2%

Coverage calculated from unit tests only

@github-actions
Copy link
Contributor

github-actions bot commented Jan 16, 2026

AgentReady Code Review - PR #265

Summary

Status: ✅ APPROVE with minor suggestions
Score Impact: Positive - enhances attribute assessment capability
Security: ✅ PASS - Path traversal protection implemented correctly

This PR adds comprehensive support for AGENTS.md and @ reference syntax to the CLAUDEmdAssessor, enabling cross-tool compatibility while maintaining security.

🎯 AgentReady Attribute Compliance

✅ Strengths

1. Test Coverage (test_coverage) - Score: 95/100

  • 14 comprehensive unit tests covering all new functionality
  • Security test cases for path traversal prevention
  • Edge cases well covered (symlinks, @ references, missing files)
  • Test file: tests/unit/test_assessors_documentation.py (+441 lines)

2. Type Annotations (type_annotations) - Score: 100/100

  • All new methods have proper type hints
  • Uses modern Python 3.11+ syntax
  • Return types explicitly declared

3. Inline Documentation (inline_documentation) - Score: 100/100

  • Comprehensive docstrings on all new methods
  • Security considerations documented
  • Pass criteria clearly explained

4. Code Complexity (code_complexity) - Score: 90/100

  • Well-factored with helper methods
  • Main assess() method is complex but readable
  • Consider: Could extract symlink detection logic to helper method

5. Standard Project Layout (standard_layout) - Score: 100/100

  • Tests properly organized in tests/unit/
  • Follows existing project structure conventions

🔒 Security Analysis

✅ Excellent Path Traversal Protection

Location: src/agentready/assessors/documentation.py:216-220

Assessment:

  • ✅ Correctly rejects ../ path traversal attempts
  • ✅ Correctly rejects absolute paths
  • ✅ Validated by comprehensive security tests
  • ✅ Defense-in-depth: Path.resolve validates file exists within repo

💎 Code Quality

✅ Excellent Practices

  1. Error Handling - Gracefully handles FileNotFoundError, OSError, UnicodeDecodeError
  2. TOCTOU Prevention - Uses try-except around file reads instead of existence checks
  3. Readability - Clear variable names, user-friendly evidence messages
  4. Backwards Compatibility - Maintains existing behavior, no breaking changes

📝 Minor Suggestions (Optional)

  1. Extract symlink detection to helper method (readability)
  2. Cache AGENTS.md read to avoid duplicate I/O (performance)
  3. Add inline comment for regex pattern (documentation)

🧪 Testing Assessment

✅ Comprehensive Test Coverage

Test Categories:

  1. ✅ Happy paths (CLAUDE.md exists, symlinks, @ references)
  2. ✅ Edge cases (minimal files, missing references, subdirectories)
  3. ✅ Security (path traversal, absolute paths)
  4. ✅ Cross-tool compatibility (both files present)
  5. ✅ Helper method testing

Test Quality: 10/10

  • Clear test names describe scenarios
  • Proper test isolation using tmp_path fixtures
  • Assertions verify both score and evidence messages
  • Security tests validate rejection of malicious paths

📊 Scoring Logic Review

✅ Well-Designed Scoring Strategy

Scenario Score Reasoning
CLAUDE.md >50 bytes 100 Perfect - primary file exists
CLAUDE.md symlink to AGENTS.md 100 Perfect - cross-tool compatible
CLAUDE.md with @AGENTS.md 100 Perfect - indirection supported
AGENTS.md only 90 Good but missing CLAUDE.md
CLAUDE.md <50 bytes, invalid @ 25 Partial credit
Neither file exists 0 Fail - no configuration

Assessment: Scoring is fair, incentivizes best practices, and provides partial credit appropriately.

✅ Final Verdict

Recommendation: APPROVE

This PR demonstrates excellent software engineering practices:

✅ Security: Robust path traversal protection
✅ Testing: Comprehensive coverage with security validation
✅ Code Quality: Well-factored, readable, maintainable
✅ Documentation: Clear docstrings and user guidance
✅ Backwards Compatibility: No breaking changes
✅ AgentReady Attributes: High compliance across all measured attributes

Risk Assessment: LOW

  • No breaking changes
  • Security considerations properly handled
  • Extensive test coverage validates behavior
  • Error handling prevents crashes

📈 AgentReady Score Impact

Before: CLAUDEmdAssessor only recognized CLAUDE.md
After: Supports AGENTS.md, symlinks, @ references

Impact: Enables more flexible repository configurations and encourages cross-tool compatibility

Estimated Score Improvement: +5-10 points for repos with AGENTS.md

Reviewed by: AgentReady Code Review (Claude Sonnet 4.5)
Review Date: 2026-01-16
PR: #265

@chambridge chambridge merged commit 450ec25 into ambient-code:main Jan 16, 2026
10 checks passed
@chambridge chambridge deleted the feature/244-agents-md-support branch January 16, 2026 19:02
github-actions bot pushed a commit that referenced this pull request Jan 16, 2026
@semantic-release-bot
chore(release): 2.23.0 [skip ci]
b643803 
# [2.23.0](v2.22.3...v2.23.0) (2026-01-16)

### Features

* **assessors:** support AGENTS.md and @ references in CLAUDEmdAssessor ([#265](#265)) ([450ec25](450ec25)), closes [#244](#244)
@github-actions
Copy link
Contributor

github-actions bot commented Jan 16, 2026

🎉 This PR is included in version 2.23.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[FEATURE] Allow CLAUDE.md to link to AGENTS.md

1 participant

@chambridge